package cn.harry.cabinet.hardware

/**
 * 串口通信监听接口
 * 提供串口通信过程中的各种事件回调
 */
interface SerialCommunicationListener {
    
    /**
     * 连接成功回调
     * @param devicePath 串口设备路径
     * @param config 串口配置信息
     */
    fun onConnectionSuccess(devicePath: String, config: SerialPortManager.SerialConfig)
    
    /**
     * 连接失败回调
     * @param devicePath 串口设备路径
     * @param error 错误信息
     * @param exception 异常对象（可选）
     */
    fun onConnectionFailed(devicePath: String, error: String, exception: Exception? = null)
    
    /**
     * 连接关闭回调
     * @param devicePath 串口设备路径
     * @param reason 关闭原因
     */
    fun onConnectionClosed(devicePath: String, reason: String)
    
    /**
     * 发送数据回调
     * @param devicePath 串口设备路径
     * @param data 发送的数据
     * @param success 发送是否成功
     */
    fun onDataSent(devicePath: String, data: ByteArray, success: Boolean)
    
    /**
     * 接收数据完成回调
     * @param devicePath 串口设备路径
     * @param data 接收到的数据
     * @param timestamp 接收时间戳
     */
    fun onDataReceived(devicePath: String, data: ByteArray, timestamp: Long)
    
    /**
     * 通信超时回调
     * @param devicePath 串口设备路径
     * @param operation 超时的操作类型
     * @param timeoutMs 超时时间（毫秒）
     */
    fun onCommunicationTimeout(devicePath: String, operation: String, timeoutMs: Long)
    
    /**
     * 通信错误回调
     * @param devicePath 串口设备路径
     * @param errorType 错误类型
     * @param errorMessage 错误消息
     * @param exception 异常对象（可选）
     */
    fun onCommunicationError(devicePath: String, errorType: ErrorType, errorMessage: String, exception: Exception? = null)
    
    /**
     * 连接状态变化回调
     * @param devicePath 串口设备路径
     * @param oldState 旧状态
     * @param newState 新状态
     */
    fun onConnectionStateChanged(devicePath: String, oldState: SerialPortManager.ConnectionState, newState: SerialPortManager.ConnectionState)
    
    /**
     * 设备状态变化回调
     * @param deviceAddress 设备地址
     * @param deviceName 设备名称
     * @param oldStatus 旧状态
     * @param newStatus 新状态
     */
    fun onDeviceStatusChanged(deviceAddress: Byte, deviceName: String, oldStatus: String, newStatus: String)
    
    /**
     * 错误类型枚举
     */
    enum class ErrorType {
        IO_ERROR,           // IO错误
        PERMISSION_DENIED,  // 权限被拒绝
        DEVICE_NOT_FOUND,   // 设备未找到
        PROTOCOL_ERROR,     // 协议错误
        CHECKSUM_ERROR,     // 校验和错误
        BUFFER_OVERFLOW,    // 缓冲区溢出
        UNKNOWN_ERROR       // 未知错误
    }
}

/**
 * 空实现的串口通信监听器基类
 * 可以继承此类并重写需要的方法，避免实现所有接口方法
 */
abstract class SerialCommunicationListenerAdapter : SerialCommunicationListener {
    
    override fun onConnectionSuccess(devicePath: String, config: SerialPortManager.SerialConfig) {}
    
    override fun onConnectionFailed(devicePath: String, error: String, exception: Exception?) {}
    
    override fun onConnectionClosed(devicePath: String, reason: String) {}
    
    override fun onDataSent(devicePath: String, data: ByteArray, success: Boolean) {}
    
    override fun onDataReceived(devicePath: String, data: ByteArray, timestamp: Long) {}
    
    override fun onCommunicationTimeout(devicePath: String, operation: String, timeoutMs: Long) {}
    
    override fun onCommunicationError(devicePath: String, errorType: SerialCommunicationListener.ErrorType, errorMessage: String, exception: Exception?) {}
    
    override fun onConnectionStateChanged(devicePath: String, oldState: SerialPortManager.ConnectionState, newState: SerialPortManager.ConnectionState) {}
    
    override fun onDeviceStatusChanged(deviceAddress: Byte, deviceName: String, oldStatus: String, newStatus: String) {}
}